Using object prefab placeholders

Object prefab placeholders contain a single root node that can be any object in the Project > Prefabs. In your project you can treat an object prefab placeholder like any other object. Once referred to in a project, the placeholder instantiates an exact copy of that prefab.

Use prefabs (prefabricated templates) to create reusable content in your project.

For example, use prefabs to:

• Modularize your Kanzi project
• Separate your project into multiple views (UI screens)
• Control the loading of and application start-up times of your Kanzi application
• Create different themes for the UI in your Kanzi application
• Localize your Kanzi application

To use object prefab placeholders, first create a prefab object. See Creating a prefab object.

Creating a prefab object

To create a prefab object:

1. Right-click Project > Prefabs and create any object you want to use more than once in your project.
   For example, create an Empty Node, and add to it a Plane and a Text Block.
   
2. Set the properties of the objects in the prefab you created.
   For example, create a custom property, add it to the Empty Node, and use a binding to set the text in the Text Block.
   You can reuse this object as many times as you need in your project with an Object Prefab Placeholder. Whenever you make a change to the prefab, that change is visible everywhere in your project where you use that prefab. See Using prefab objects in your project.

or

You can make any part of your project hierarchy into a prefab, by dragging the root of the hierarchy to the prefabs folder.

Kanzi Studio creates a prefab template for the hierarchy and replaces the original hierarchy with an instance of the prefab.

Using prefab objects in your project

To use prefabs objects in your project:

1. Create a prefab. See Creating a prefab object.
   For example, create an Empty Node, and add to it a Plane and a Text Block.
2. In the Project right-click in a scene where you want to use the prefab and select Create > Object Prefab Placeholder.
3. In the Properties set the Prefab Template property to the prefab you created in the first step.
   To make prefabs really useful, you can modify the properties of prefab instances. See Modifying properties of prefab instances with bindings.

When using prefabs keep in mind that:

• You can duplicate a prefab placeholder like any other object.
• All properties you add to a prefab placeholder override the values you set in the prefab.
• When referencing objects inside a prefab (for example, in a message trigger or a property binding), use relative paths. Do not use the prefab itself as a target path for any messages or animations. Use only prefab placeholders.

Editing prefabs

You can edit the prefabs only in the prefab template itself or in the root object of a prefab instance. The objects inside a prefab instance are gray, if defined under the screen’s hierarchy.

Use the root object of the prefab instance to access the whole prefab instance. If you want to override the content inside the prefab instance, apply the changes to the root object, and forward them to the target property using bindings. If the value is a resource, you can use resource IDs to override the values provided in the prefab template’s dictionary.

Using triggers to add prefabs or replace objects with prefabs

You can use trigger actions to add prefabs or replace objects with prefabs in your project. For example, you can use Click trigger of a button object to instantiate a prefab, or to replace an existing layer with a prefab layer.

To use triggers to add or replace prefabs:

1. In the Project create a prefab object. See Creating a prefab object.
   For example, create an empty layer, and add to it a text layer.
2. In the Project create an object which you want to use as a trigger.
   For example, create a button in a visible scene. See Using buttons.
3. In the Properties add a trigger to the object you created in the previous step.
   For example, if you created a button, use the Click trigger. See Using triggers.
4. In the Properties click the Add drop-down menu for your message type and select an action. Use:
   • Instantiate Prefab to add the prefab to your application.
   • Replace Node to replace an existing object with a prefab. When using Replace Node always set the Node To Be Replaced using a relative path.
   For example, use Instantiate Prefab action.
   
5. In the Argument Editor set:
   • Source Prefab to the prefab you want to instantiate
   • Target Node to the object where you want to instantiate the prefab
     
6. Click Save.

Modifying properties of prefab instances with bindings

A prefab can consist a tree of objects, each with their own properties. However, a prefab instance provides access only to the properties of the root object. To change the properties inside the hierarchy of a prefab instance, add to the root object the properties you want to modify, and bind to those properties from the objects in the prefab. This can be done by defining custom properties and bindings.

This procedure shows how to use bindings and custom properties so that instances of the prefab can have individual values.

To modify properties of prefab instances with bindings:

1. Create a prefab object. See Creating a prefab object.
   For example, create an Empty Node, and add to it a Plane and a Text Block.
2. Create a custom property type. See Creating custom property types.
   For example, create a custom property PrefabText and set:
   • Data Type property to Text
   • Property Hosts property to at least 3D Object Node
3. In the Project select the root object of your prefab in the Prefabs, in the Properties click Add Properties and add the custom property you just created.
   If you use more than one property, add all the properties you want to modify with bindings.
   For example, if the root of your prefab is an Empty Node, add the property to the Empty Node.
4. In your prefab, create a binding from an object inside the prefab to the custom property. See Using bindings.
   For example, if you created a property that sets a text value and your prefab contains a Text Block, in the Project select the Text Block in the prefab, and in the Properties create a binding to the property in the Empty Node.
5. Instantiate your prefab object in your project with an Object Prefab Placeholder. See Using prefab objects in your project.
6. In the Project select the prefab instance, and in the Properties add all the properties for which you created bindings in the prefab.
   Now you can modify the custom property value for the instance of the prefab, by setting its value in the prefab placeholder.

See also

Creating and editing prefabs

Using layer prefab placeholders

Prefabs

Open topic with navigation